<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Creating a database environment</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="env.html" title="Chapter 10.  The Berkeley DB Environment" />
    <link rel="prev" href="env.html" title="Chapter 10.  The Berkeley DB Environment" />
    <link rel="next" href="env_size.html" title="Sizing a database environment" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Creating a database
        environment</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="env.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 10.  The Berkeley DB Environment </th>
          <td width="20%" align="right"> <a accesskey="n" href="env_size.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="env_create"></a>Creating a database
        environment</h2>
          </div>
        </div>
      </div>
      <p>
        The Berkeley DB environment is created and described by the
        <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> and <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> interfaces. In situations where
        customization is desired, such as storing log files on a
        separate disk drive or selection of a particular cache size,
        applications must describe the customization by either
        creating an environment configuration file in the environment
        home directory or by arguments passed to other <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle
        methods.
    </p>
      <p>
        Once an environment has been created, database files
        specified using relative pathnames will be named relative to
        the home directory. Using pathnames relative to the home
        directory allows the entire environment to be easily moved,
        simplifying restoration and recovery of a database in a
        different directory or on a different system.
    </p>
      <p>
        Applications first obtain an environment handle using the
        <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> method, then call the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method which
        creates or joins the database environment. There are a number
        of options you can set to customize <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> for your
        environment. These options fall into four broad
        categories:
    </p>
      <div class="variablelist">
        <dl>
          <dt>
            <span class="term">Subsystem Initialization:</span>
          </dt>
          <dd>
                These flags indicate which Berkeley DB
                subsystems will be initialized for the environment,
                and what operations will happen automatically when
                databases are accessed within the environment. The
                flags include <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a>,
                <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOG" class="olink">DB_INIT_LOG</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>, and <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a>. The
                <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a> flag does initialization for Berkeley DB
                Concurrent Data Store applications. (See <a class="xref" href="cam.html#cam_intro" title="Concurrent Data Store introduction">Concurrent Data Store
        introduction</a>
                for more information.) The rest of the flags
                initialize a single subsystem; that is, when
                <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> is specified, applications reading and
                writing databases opened in this environment will be
                using locking to ensure that they do not overwrite
                each other's changes.
            </dd>
          <dt>
            <span class="term">Recovery options:</span>
          </dt>
          <dd>
                These flags, which include <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> and
                <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">DB_RECOVER_FATAL</a>, indicate what recovery is to be
                performed on the environment before it is opened for
                normal use.
            </dd>
          <dt>
            <span class="term">Naming options:</span>
          </dt>
          <dd>
                These flags, which include <a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON" class="olink">DB_USE_ENVIRON</a> and
                <a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON_ROOT" class="olink">DB_USE_ENVIRON_ROOT</a>, modify how file naming happens
                in the environment.
            </dd>
          <dt>
            <span class="term">Miscellaneous:</span>
          </dt>
          <dd>
                Finally, there are a number of miscellaneous
                flags, for example, <a href="../api_reference/C/dbopen.html#open_DB_CREATE" class="olink">DB_CREATE</a> which causes
                underlying files to be created as necessary. See the
                <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> manual pages for further
                information.
            </dd>
        </dl>
      </div>
      <p>
        Most applications either specify only the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>
        flag or they specify all four subsystem initialization flags
        (<a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOG" class="olink">DB_INIT_LOG</a>, and
        <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a>). The former configuration is for applications
        that simply want to use the basic Access Method interfaces
        with a shared underlying buffer pool, but don't care about
        recoverability after application or system failure. The latter
        is for applications that need recoverability. There are
        situations in which other combinations of the initialization
        flags make sense, but they are rare.
    </p>
      <p>
        The <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> flag is specified by applications that want
        to perform any necessary database recovery when they start
        running. That is, if there was a system or application failure
        the last time they ran, they want the databases to be made
        consistent before they start running again. It is not an error
        to specify this flag when no recovery needs to be done.
    </p>
      <p>
        The <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">DB_RECOVER_FATAL</a> flag is more special-purpose. It
        performs catastrophic database recovery, and normally requires
        that some initial arrangements be made; that is, archived log
        files be brought back into the filesystem. Applications should
        not normally specify this flag. Instead, under these rare
        conditions, the <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility should be used.
    </p>
      <p>
        The following is a simple example of a function that opens a
        database environment for a transactional program.
    </p>
      <a id="prog_env27"></a>
      <pre class="programlisting">DB_ENV *
db_setup(char *home, char *data_dir, FILE *errfp, char *progname)
    {
    DB_ENV *dbenv;
    int ret;

    /*
     * Create an environment and initialize it for additional error
     * reporting.
     */
    if ((ret = db_env_create(&amp;dbenv, 0)) != 0) {
        fprintf(errfp, "%s: %s\n", progname, db_strerror(ret));
        return (NULL);
    }
    dbenv-&gt;set_errfile(dbenv, errfp);
    dbenv-&gt;set_errpfx(dbenv, progname);

    /*
     * Specify the shared memory buffer pool cachesize: 5MB.
     * Databases are in a subdirectory of the environment home.
     */
    if ((ret = dbenv-&gt;set_cachesize(dbenv, 0, 
                                     5 * 1024 * 1024, 0)) != 0) {
        dbenv-&gt;err(dbenv, ret, "set_cachesize");
        goto err;
    }
    if ((ret = dbenv-&gt;add_data_dir(dbenv, data_dir)) != 0) {
        dbenv-&gt;err(dbenv, ret, "add_data_dir: %s", data_dir);
        goto err;
    }

    /* Open the environment with full transactional support. */
    if ((ret = dbenv-&gt;open(dbenv, home, DB_CREATE | DB_INIT_LOG | 
                DB_INIT_LOCK | DB_INIT_MPOOL | 
                DB_INIT_TXN, 0)) != 0) {
        dbenv-&gt;err(dbenv, ret, "environment open: %s", home);
        goto err;
    }

    return (dbenv);

err:    (void)dbenv-&gt;close(dbenv, 0);
    return (NULL);
}</pre>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="env.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="env.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="env_size.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 10.  The Berkeley DB Environment  </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Sizing a database environment</td>
        </tr>
      </table>
    </div>
  </body>
</html>
